home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 November: Tool Chest / Dev.CD Nov 00 TC Disk 1.toast / Tool Chest / Testing & Debugging / Debuggers & dcmds / MacsBug 6.6 / Building dcmds / dcmd Includes / Dcmd.h < prev    next >
Encoding:
C/C++ Source or Header  |  1999-10-20  |  9.2 KB  |  326 lines  |  [TEXT/MPS ]
  1. /*
  2.      File:        dcmd.h
  3.  
  4.      Contains:    MacsBug debugger command interface.
  5.  
  6.      Version:    Technology:    MacsBug
  7.                  Release:    MacsBug 6.6
  8.  
  9.      Copyright:    © 1988, 1994-1999, 1999 by Apple Computer, Inc., All Rights Reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __DCMD__
  18. #define __DCMD__
  19.  
  20. #ifndef __MACTYPES__
  21. #include <MacTypes.h>
  22. #endif
  23.  
  24. #ifndef __MACHINEEXCEPTIONS__
  25. #include <MachineExceptions.h>
  26. #endif
  27.  
  28.  
  29.  
  30.  
  31. #if PRAGMA_ONCE
  32. #pragma once
  33. #endif
  34.  
  35. #ifdef __cplusplus
  36. extern "C" {
  37. #endif
  38.  
  39. #if PRAGMA_IMPORT
  40. #pragma import on
  41. #endif
  42.  
  43. #if PRAGMA_STRUCT_ALIGN
  44.     #pragma options align=mac68k
  45. #elif PRAGMA_STRUCT_PACKPUSH
  46.     #pragma pack(push, 2)
  47. #elif PRAGMA_STRUCT_PACK
  48.     #pragma pack(2)
  49. #endif
  50.  
  51. /* Possible requests from the debugger to the command*/
  52. enum {
  53.     dcmdInit                    = 0,                            /* Initialize the Dcmd */
  54.     dcmdDoIt                    = 1,                            /* Normal Dcmd execution */
  55.     dcmdHelp                    = 2,                            /* Display help for Dcmd */
  56.                                                                 /* Requests added to MacsBug in 6.5d10 that are only sent to format 3 or newer dcmds. */
  57.     dcmdSecondaryInit            = 3,                            /* Second time to init after all System patches have been loaded */
  58.     dcmdShutdown                = 4,                            /* Dcmd should remove any patches (if possible) */
  59.     dcmdGetInfo                    = 5                                /* Return dcmd version and pointer to help text */
  60. };
  61.  
  62.  
  63. /* 68K register file indices into the RegisterFile.*/
  64. enum {
  65.     D0Register                    = 0,
  66.     D1Register                    = 1,
  67.     D2Register                    = 2,
  68.     D3Register                    = 3,
  69.     D4Register                    = 4,
  70.     D5Register                    = 5,
  71.     D6Register                    = 6,
  72.     D7Register                    = 7,
  73.     A0Register                    = 8,
  74.     A1Register                    = 9,
  75.     A2Register                    = 10,
  76.     A3Register                    = 11,
  77.     A4Register                    = 12,
  78.     A5Register                    = 13,
  79.     A6Register                    = 14,
  80.     A7Register                    = 15,
  81.     PCRegister                    = 16,
  82.     SRRegister                    = 17                            /* SR is only 16 bits and is stored in the high word */
  83. };
  84.  
  85.  
  86. /* Heap block types*/
  87. enum {
  88.     freeBlock                    = 0,
  89.     nonrelocatableBlock            = 1,
  90.     relocatableBlock            = 2
  91. };
  92.  
  93.  
  94. /*    The format of the 68K registers passed to the dcmd.*/
  95. typedef long                             RegisterFile[18];
  96. typedef long *                            RegisterFilePtr;
  97.  
  98. /* Structure used to pass information to and from the dcmd.*/
  99.  
  100. struct dcmdBlock {
  101.     RegisterFilePtr                 registerFile;                /* pointer to 68K CPU register set */
  102.     short                             request;                    /* what action we are requested to take */
  103.     Boolean                         aborted;                    /* Set to true if the user types a key while scrolling */
  104.     Boolean                         pad1;                        /* align to word boundary */
  105.     UInt32                             macsBugVersion;                /* version of MacsBug we are running under */
  106.     UInt16                             maxCallback;                /* maximum valid callback we can make */
  107.     UInt8                             currentISA;                    /* ISA of current PC */
  108.     UInt8                             pad2;                        /* align to word boundary */
  109.     ExceptionInformationPowerPC *    theException;                /* Pointer to PowerPC machine state if ISA is PowerPC */
  110.     Ptr                             requestIOBlock;                /* general-purpose input/output data block pointer */
  111. };
  112. typedef struct dcmdBlock                dcmdBlock;
  113. typedef dcmdBlock *                        dcmdBlockPtr;
  114.  
  115.  
  116. struct GetInfoRequestBlock {
  117.     Str255                             usageStr;
  118.     Str255                             creditsStr;
  119.     NumVersion                         dcmdVersion;
  120. };
  121. typedef struct GetInfoRequestBlock        GetInfoRequestBlock;
  122. typedef GetInfoRequestBlock *            GetInfoRequestBlockPtr;
  123.  
  124. /*
  125.     These are some useful macros for filling in format 3 version and string fields.
  126.  */
  127.  
  128. #define dcmdFillVersion(paramPtr, version) \
  129.         * (long *) &((GetInfoRequestBlockPtr) (paramPtr)->requestIOBlock)->dcmdVersion = (version)
  130.  
  131.  
  132. #define dcmdFillString(paramPtr, which, theStr) \
  133.         BlockMoveData(theStr, &((GetInfoRequestBlockPtr) paramPtr->requestIOBlock)->which, (theStr)[0]+1)
  134.  
  135.  
  136. /*
  137.     MacsBug callback routines that can be called by the dcmd.
  138.  */
  139.  
  140. /*
  141.     Draw the text in the Pascal string as one or more lines separated by CR's.
  142.     Each line causes the MacsBug display to be scrolled and the new line to be
  143.     drawn at the bottom. If the user types a key while scrolling then the aborted
  144.     flag is set telling the command to terminate immediately.
  145.  */
  146. EXTERN_API( void )
  147. dcmdDrawLine                    (ConstStr255Param         str);
  148.  
  149.  
  150. /*
  151.     Draw the text in the Pascal string as a continuation of the current line.
  152.     CR's are not given special treatment.
  153.  */
  154. EXTERN_API( void )
  155. dcmdDrawString                    (ConstStr255Param         str);
  156.  
  157.  
  158. /*
  159.     Draw a given number of characters starting from the given pointer as a 
  160.     continuation of the current line. CR's are not given special treatment.
  161.  */
  162. EXTERN_API( void )
  163. dcmdDrawText                    (char *                    text,
  164.                                  short                     length);
  165.  
  166.  
  167. /*
  168.     Scrolls the MacsBug display up one line leaving a blank line at the bottom.
  169.  */
  170. EXTERN_API( void )
  171. dcmdScroll                        (void);
  172.  
  173.  
  174. /*
  175.     Display the Pascal string in the command line area and wait for a key to be pressed.
  176.     Return TRUE if the user typed Return. All other keys return FALSE. MacsBug saves this
  177.     key and adds it to the command line once the current command completes. Typing any
  178.     key other than Return sets the aborted flag and tells the command to terminate immediately.
  179.  */
  180. EXTERN_API( Boolean )
  181. dcmdDrawPrompt                    (ConstStr255Param         str);
  182.  
  183.  
  184. /*
  185.     Get the current command line position.
  186.  */
  187. EXTERN_API( short )
  188. dcmdGetPosition                    (void);
  189.  
  190.  
  191. /*
  192.     Set the current command line position. This should only be set to a value returned 
  193.     by dcmdGetPosition.
  194.  */
  195. EXTERN_API( void )
  196. dcmdSetPosition                    (short                     pos);
  197.  
  198.  
  199. /*
  200.     Return the next character on the command line or CR if the entire line has been scanned
  201.  */
  202. EXTERN_API( short )
  203. dcmdGetNextChar                    (void);
  204.  
  205.  
  206. /*
  207.     Return the next character on the command line or CR if the entire line has been scanned.
  208.     However, the current command line position is not changed.
  209.  */
  210. EXTERN_API( short )
  211. dcmdPeekAtNextChar                (void);
  212.  
  213.  
  214. /*
  215.     Copy all characters from the command line to the parameter string until a delimiter
  216.     is found or the end of the command line is reached. A delimiter is either a space,
  217.     a comma or a CR. Both single and double quoted strings are allowed on the command
  218.     line. However, the leading and trailing quotes must be of the same type. The parameter
  219.     string is returned without the quotes. This function returns the delimiter.
  220.  */
  221. EXTERN_API( short )
  222. dcmdGetNextParameter            (Str255                 str);
  223.  
  224.  
  225. /*
  226.     Parse the command line for the next expression. All expressions are evaluated to 32 bits.
  227.     This function returns the delimiter after the expression. The possible delimiters are
  228.     space, comma and CR. Space is not treated as a delimiter in the middle of expressions,
  229.     unless it's before a binary '-' (minus). For instance, '1 + 2' will return a value of 3
  230.     and the delimiter will be the char following the 2. '1 - 2' will return a value of 1
  231.     and the delimeter is the space character before the '-'. This is done so that built-in
  232.     commands and dcmds can properly parse '-x' options. The return parameter 'ok' tells if
  233.     the expression was parsed successfully as far as syntax is concerned.
  234.  */
  235. EXTERN_API( short )
  236. dcmdGetNextExpression            (long *                    value,
  237.                                  Boolean *                ok);
  238.  
  239.  
  240. /*
  241.     Copy the break message MacsBug displayed the last time it was entered into str.
  242.     This may contain multiple lines separated by CR's.
  243.  */
  244. EXTERN_API( void )
  245. dcmdGetBreakMessage                (Str255                 str);
  246.  
  247.  
  248. /*
  249.     Return a symbolic representation for address in str. If no symbol can be found
  250.     then an empty string is returned. The format of the symbol returned is Name+00000.
  251.  */
  252. EXTERN_API( void )
  253. dcmdGetNameAndOffset            (long                     address,
  254.                                  Str255                 str);
  255.  
  256.  
  257. /*
  258.     Return the trap name for the trap number. If no symbol can be found
  259.     then an empty string is returned.
  260.  */
  261. EXTERN_API( void )
  262. dcmdGetTrapName                    (short                     trapNumber,
  263.                                  Str255                 trapName);
  264.  
  265.  
  266. /*
  267.     Return a pointer the macro name for the given value. If no macro can be found
  268.     then a nil is returned.
  269.  */
  270. EXTERN_API( StringPtr )
  271. dcmdGetMacroName                (long                     value);
  272.  
  273.  
  274. /*
  275.     When a debugger command is called, the debugger's world (low memory) is installed.
  276.     Commands that want to reference the user's world can swap back and forth between the
  277.     two worlds by making this call. This procedure does nothing in MacsBug; there is no
  278.     distinction between user and debugger worlds. It is included to support other
  279.     debuggers that might want to take advantage of it.
  280.  */
  281. EXTERN_API( void )
  282. dcmdSwapWorlds                    (void);
  283.  
  284.  
  285. /*
  286.     Toggle between the user and debugger displays. The first call restores the user's actual screen.
  287.     The second call restores the debugger's screen.
  288.  */
  289. EXTERN_API( void )
  290. dcmdSwapScreens                    (void);
  291.  
  292.  
  293. /*
  294.     Walk through the blocks in the current heap, calling DoThis for each block.
  295.     The blockAddress and blockLength pertain to the data in the heap block, not including
  296.     the block header. The addrOfMasterPtr is the master pointer's location in the heap,
  297.     not the value of the master ptr. The blockType is defined by the constants freeBlock,
  298.     nonrelocatableBlock and relocatableBlock. The booleans locked, purgeable and resource
  299.     reflect the state of the block.
  300.  */
  301. typedef CALLBACK_API( void , DoThisPtr )(long blockAddress, long blockLength, long addrOfMasterPtr, short blockType, Boolean locked, Boolean purgeable, Boolean resource);
  302. EXTERN_API( void )
  303. dcmdForAllHeapBlocks            (DoThisPtr                 DoThis);
  304.  
  305.  
  306. #if PRAGMA_STRUCT_ALIGN
  307.     #pragma options align=reset
  308. #elif PRAGMA_STRUCT_PACKPUSH
  309.     #pragma pack(pop)
  310. #elif PRAGMA_STRUCT_PACK
  311.     #pragma pack()
  312. #endif
  313.  
  314. #ifdef PRAGMA_IMPORT_OFF
  315. #pragma import off
  316. #elif PRAGMA_IMPORT
  317. #pragma import reset
  318. #endif
  319.  
  320. #ifdef __cplusplus
  321. }
  322. #endif
  323.  
  324. #endif /* __DCMD__ */
  325.  
  326.